.TH E1432_CREATE_CHANNEL_GROUP 3 E1432
.SH NAME
e1432_create_channel_group \- Create a group of E1432 channels
.IX e1432_create_channel_group(3) 3
.SH SYNOPSIS
.cS
SHORTSIZ16 e1432_create_channel_group(E1432ID hw, SHORTSIZ16 nchan,
                                      SHORTSIZ16 *chan_list)
.cE
.SH DESCRIPTION
\fIe1432_create_channel_group\fR creates and initializes a channel
group.  A channel group allows you to issue commands to several E1432
channels at once, simplifying system setup.  You can overlap channel
groups.  The state of an individual E1432 channel that is in more than
one channel group, is determined by the most recent operation
performed on any group to which this channel belongs.

As a side effect, this function makes all input and tach channels in
the channel group active, and all source channels in the channel group
inactive.  Unlike the E1431 library, this function does not inactivate
other channels within the modules that the channels are in.  Also
unlike the E1431 library, this function does not preset the channels
in the new group.

An additional side effect of this function is that it resets the
"auto_group_meas" parameter for each module that has a channel in the
channel list.  Most applications use the default value of
"auto_group_meas", so most applications will not care about this.  See
\fIe1432_set_auto_group_meas\fR for details about this parameter.

This function dynamically allocates memory to keep track of the groups
which have been created.  This memory can be freed by
\fIe1432_delete_channel_group\fR and
\fIe1432_delete_all_chan_groups\fR.

\fIhw\fR must be the result of a successful call to
\fIe1432_assign_channel_numbers\fR, and specifies the group of
hardware to talk to.

\fInchan\fR is the count of channels passed in the third parameter,
\fIchan_list\fR.  This number should be between \fB0\fR and the
maximum number of channels available.

\fIchan_list\fR is the pointer to the list of logical channels
identifiers of the group to be created.  This list must be in
ascending order and contain no repeats.  If \fIchan\fR is zero, then
this parameter is ignored and can be set to NULL.

To supply the ID of an input channel, the input channel number is
given as an argument to the \fBE1432_INPUT_CHAN()\fR macro.  For
backwards compatibility with the E1431, the macro currently does
nothing.  To supply the ID of a source channel, the source channel
number is given as an argument to the \fBE1432_SOURCE_CHAN()\fR macro.
To supply the ID of a tach/trigger channel, the tach/trigger channel
number is given as an argument to the \fBE1432_TACH_CHAN()\fR macro.

It is legal to have a mixture of input, source, and tach channels in
one group.  It is legal to create a group that has no channels in it.

As an example, to create a group consisting of the first three input
channels and the eighth and ninth input channels, the code would like
something like this:
.cS

 SHORTSIZ16 chan_list[5];
 SHORTSIZ16 input_group;

 chan_list[0] = E1432_INPUT_CHAN(1);
 chan_list[1] = E1432_INPUT_CHAN(2);
 chan_list[2] = E1432_INPUT_CHAN(3);
 chan_list[3] = E1432_INPUT_CHAN(8);
 chan_list[4] = E1432_INPUT_CHAN(9);
 input_group = e1432_create_channel_group(hw, 5, chan_list);

.cE
To create a group consisting of the first two source channels, the
code would look something like this:
.cS

 SHORTSIZ16 chan_list[2];
 SHORTSIZ16 source_group;

 chan_list[0] = E1432_SOURCE_CHAN(1);
 chan_list[1] = E1432_SOURCE_CHAN(2);
 source_group = e1432_create_channel_group(hw, 2, chan_list);

.cE
.SH "RESET VALUE"
Not applicable.
.SH "RETURN VALUE"
If successful, this function returns the \fIID\fR of the group that
was created, which is then used to reference the channel group in most
other functions in this library.  Because a group ID is always
negative, if an error occurs a positive error number is returned by
this function.  This is the only function that returns a positive
error number.
.SH "SEE ALSO"
.na
e1432_assign_channel_numbers, e1432_channel_group_add,
e1432_channel_group_remove, e1432_delete_channel_group,
e1432_set_auto_group_meas, e1432_id(5)
.ad
